A thought.

One of the open feature requests on this repo relates to multiple yaml documents embedded in a single file.

While this is generic enough to enable parsing additional/extended serialisation formats where there is a one-to-one mapping from file to document, is this flexible enough to allow someone to implement multi-doc yaml files or something like ndjson? I think no.

While it is not a breaking change, how could I modify this to enable that use-case?

Another thought: In a world where multiple documents could live in one file, a Object<string, ValidationResult> does not make sense for output. It should be an Array<ValidationResult> (which implies a breaking change to the JSON output format).

Gah.

..and then a third thought:

One option is to deal with this now. If you have to make a breaking release now, what else would you change in it?

Another option is to say: For the moment there is a one-to-one mapping between file and document and kick this can down the road. If you do that, how can you design the current interface now in such a way that the impact of that future change is minimal?

OK. I think the most intuitive way to deal with this is:

• Change the hook name to parseFile()
• Introduce some kind of ParseResult or Document type (which is just a thin wrapper object). The key thing here is we need to be able to easily tell how many of them we got back, which we can't really do with primitive types. The top-level construct of a document could be an array.
• Allow parseFile() to return either a single Document or an array of Document objects

and then

• modify the internals to be able to deal with each document in turn
• modify the internals handle the fact that one filename can map to multiple documents
• update the JSON output format
• update the results value we pass to getAllResultsLogMessage() (which will have knock-on effects to core plugins and the hypothetical sarif plugin)
• update all the documentation

and then the next release will be breaking.

I reckon you might as well do this before anything depends on the plugin interface.
Wish I had thought of this earlier though 🙁

There's actually a fair bit more nuance to this.
At the moment, log messages assume a 1-to-1 mapping between file and document. This applied to both internal messages to stderr and messages to stdout defined by getSingleResultLogMessage(). So if you want to break that assumption it has a knock-on effect there too.

You also need a notation for documents within a file. I think multidoc.yaml[0], multidoc.yaml[1] is probably fine for this.

Here's another question to think about:
I don't really want to shave this entire yak right now. Is there a way you can implement a subset of changes now such that you

• don't have to do the whole thing right now but
• it allows you to do this later without making another BC break?

OK. So I have pushed

• ffef79b
• c36ba40
• 57b1af9

which does the following things:

• rename registerDocumentParsers to registerFileParsers and parseDocument to parseFile
• Change Object<string, ValidationResult> to Array<ValidationResult> (Breaking change to JSON output format)
• Add a Document object (but for now, the only option is parseFile returns exactly one of these)

I thiiiiiink this does enough of the groundwork that I could allow parseFile() to return an array of Document objects in future and handle that internally without having to make another breaking change to the API surface.

Two things:

1. Come back to this with a fresh perspective. Have you thought this through correctly? Is the code good? Have you missed anything?
2. Given the next release must now be a major bump, is there anything else you now want to change that you were trying to avoid changing?

change https://github.com/chris48s/v8r-plugin-emoji-output/blob/main/index.js#L10